Responds to the review of #445. Covers its item 1 (repair the supported-example
contract) and item 5 (deeper assertions), plus item 3 (subprocess cleanup) and
one defect the stronger assertions surfaced.

The example was demonstrating the opposite of its claim

Confirmed before changing anything:

$ orchestrator run examples/supported/04_conditions.yaml
output/long.txt
output/short.txt        <- the "short" handler ran on the long path

handle_short was never a branch. It was the last link of a dependency chain
(check_size -> handle_long -> handle_short), so the default path fell through
into it. on_false routing worked; the example just did not express exclusive
branches — and EXPECTATIONS asserted both artifacts, pinning it in place.

Rewritten as two exclusive branches converging on a join. The long arm's
on_success: summarise jumps the short arm; the short arm is reached only by
on_false. Measured, both arms:

taken_branch used to render {{ out_dir }} — it echoed an input and said
nothing about the branch. It now reads a file the branch itself wrote.

What a case asserts now

Exit code; every artifact and its exact contents, with an unexpected file
counting as a failure; the complete outputs document; which steps completed,
were skipped and failed; and the execution levels, so "alpha and beta run in
parallel" is checked rather than asserted in a comment. checkpoints/ is named
as a run side effect and asserted directly instead of silently ignored.

Examples with a branch declare a case per branch, so the arm a default run does
not take still executes in CI.

CLI/API equivalence was nearly vacuous

The comparison dropped every step value and the entire outputs document, on
a comment claiming values embed absolute paths differing by working directory.

Measured across all 5 examples x 3 repetitions, the only differing JSON paths
are started_at, completed_at, duration, execution_id. Every step value
is byte-identical; paths inside them are relative (./output/greeting.txt).
The comment was wrong.

PipelineResult.normalized() already blanked exactly those fields and already
claimed in its docstring to be the CLI/API comparison form, so this extracts
normalize_result_payload(dict) to serve both the object and the CLI's JSON.
One definition — the test can no longer drift into comparing less than it says.

Two runtime defects the stronger assertions surfaced

A timed-out command was abandoned, not killed. asyncio.wait_for cancels
the wait, not the process, and the timeout handler never referred to the child
again:

sleep procs BEFORE: 0
run finished, exit=1
sleep procs IMMEDIATELY AFTER: 2      <- one per attempt, outliving the run

_reap() in a finally also covers the cancellation raised when a step
rather than the command times out. Closing pipes on a live loop is also what
stops the PytestUnraisableExceptionWarning at teardown that #445's review
reported.

Templates dropped a trailing newline — but only for a parameter referencing
another step:

That path alone goes through a Jinja Environment left on the default
keep_trailing_newline=False. Of 547 blocking tests, the only two affected
were the ones pinning the truncated byte. Found because the suite now asserts
exact contents; the old suite asserted the file existed.

Evidence the new tests actually work

Every new test was run against the un-fixed code:

The leak test was vacuous in its first draft, and this is how I caught it:
the marker sat in a shell comment, and sh -c "sleep 30 # marker" execs sleep
in place, dropping both the shell and the comment from argv. A renamed copy of
sleep was then SIGKILLed by macOS code signing (rc=137). It now tracks process
ancestry with psutil.

Verification

• Blocking suite 541 -> 548 passed, 13 skipped, 0 failed
• Acceptance suite 26 -> 31 tests
• PytestUnraisableExceptionWarning and ResourceWarning are now errors in
  test_supported_examples.py and test_failure_policy.py
• compileall clean; working tree clean

On the review's "13 skips vs 12" note: skips depend on which optional extras are
installed, so that number is environment-dependent rather than a discrepancy.

Deliberately not in this PR

• Non-raising fail-fast (review item 2). Agreed it is the next runtime P0,
  but it changes the execution loop, not the examples.
• Migration guide for the old {"steps":..., "outputs":...} envelope
  (item 4). docs/CLAUDE.md directs that documentation describe the code as it
  is now and that migration guides not be written unless asked.
• Issue reconciliation and catalogue expansion (items 5-6). Bookkeeping and
  new examples respectively; neither belongs in a correctness change.

Examples validating is unchanged at 8 of 116 — this PR makes the supported set
trustworthy rather than larger.

🤖 Generated with Claude Code